Mapping keys in Vim - Tutorial (Part 3)
This is the third part of the three part tutorial on mapping keys in Vim. You can read the other two parts from the following pages: * Mapping keys in Vim - Tutorial (Part 1) * Mapping keys in Vim - Tutorial (Part 2) Using maps in Vim plugins and scripts A Vim plugin or script can define new key maps to let the user invoke the commands and functions provided by the plugin. A Vim plugin can also invoke key maps defined by other Vim plugins. A plugin can choose to map any available key. But to avoid surprising (annoying) the user, it is better not to use the keys that already have pre-defined functionality in Vim. In a Vim plugin, the ":normal" command is used to execute normal mode commands. For example, the "gqip" normal mode command is used to format a paragraph. To invoke this command from a Vim plugin, the following line can be used: normal gqip If any of the keys in "gqip" is mapped, then the mapped key sequence will be executed. This may change the expected behavior of the "gqip" command. To avoid this, add the "!" suffix to the "normal" command: normal! gqip With the "!" suffix, the "normal" command executes the built-in functionality provided by Vim for the specified sequence of keys. To invoke a script local function, defined with the "s:" prefix, from a map, you have to prefix the function name with . You cannot use the "s:" prefix for the script-local function, as the map will be invoked from outside of the script context. :inoremap InsertFunc() A plugin may map one or more keys to easily invoke the functionality provided by the plugin. In the plugin functions used by these types of maps, it is advisable not to alter user Vim option settings, register contents and marks. Otherwise, the user will be surprised to see that some options are changed after invoking a plugin provided map. Map leader If the key maps provided by all the Vim plugins start with a same key, then it is easier for a user to distinguish between their own key maps and the ones provided by plugins. To facilitate this, Vim provides a special keyword that can be used in a map command. If the {lhs} key sequence of a map command starts with the string "", then Vim replaces it with the key set in the 'mapleader' variable. The default setting for the 'mapleader' variable is backslash ('\'). Note that 'mapleader' is a Vim variable and not a Vim option. The value of this variable can be changed using the 'let' command. For example, to set it to '_' (underscore), you can use the following command in your vimrc file: let mapleader = "_" Vim replaces with the 'mapleader' value only when defining the map and not when the map is invoked. This means that after several map commands are defined if the 'mapleader' variable is changed, it will not affect the previously defined maps. For example, consider the following map command defined by a plugin: nnoremap f :call JumpToFile() When defining the above command, Vim replaces with the value of the 'mapleader' variable. If the user didn't set the 'mapleader' variable then the above map can be invoked by entering \f. If the user sets the 'mapleader' to a comma (','), then it can be invoked using ,f. The prefix should be used for global mappings (applicable to all buffers) defined by a plugin. For buffer-local mappings, the prefix should be used. Vim will replace this with the value set in the 'maplocalleader' variable. The default value for this variable is backslash ('\'). The is generally used in mappings defined by a Vim filetype plugin. The 'mapleader' and 'maplocalleader' variables allow the user to choose different keys as starting keys for global mappings and buffer-local mappings defined by Vim plugins. Script maps If you want to use recursive maps in your map command, but want to use only those keys mapped in your script or plugin, then you can use the